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NAIE> Icy Benefits 
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¢ Ease of use: Icy operates as an extension to the IDL 
language regime. 
¢ Icy supports more than four-hundred CSPICE routines. 


¢ Icy calls usually correspond to the call format of the 
underlying CSPICE routine, returning IDL native data types. 


¢ Icy has some capability not available in CSPICE such as 
vectorization. 


¢ CSPICE error messages return to IDL in a form usable by the 
catch error handler construct. 
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How Does It Work? (1) 
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e The IDL environment includes an intrinsic capability to use 
external routines. 

— Icy functions as an IDL Dynamically Loadable Module (DLM). A 
DLM consists of a shared object library (icy.so/.dll) and a DLM 
text definition file (icy.dlm). 

» The shared library contains a set of IDL callable C interface routines 
that wrap a subset of CSPICE wrapper calls. 


» The text definition file lists the routines within the shared library 
and the format for the routine’s call parameters. 
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How Does It Work? (2) 
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¢ Using Icy from IDL requires you register the Icy DLM with IDL to 
access the interface routines. Several means exist to do so. 


— On Unix/Linux, start IDL from the directory containing icy.dlm and icy.so 


— From the IDL interpreter (or from a command script), execute the 
dim_register command: IDL> dim_register,’ path_to_directory_containing_icy.dlm_’ 
» Examples (Unix and Windows): 
» IDL> dlm_register, ‘/naif/icy/lib/icy.dlm’ 
» IDL> dlm_register, ‘c:\naif\icy\lib\icy.dlm’ 


— Copy icy.dlm and icy.so or icy.dll to IDL's binary directory: 


{The IDL install directory}/bin/bin.user_architecture 


» Examples (Unix and Windows): 
» cp icy.dlm icy.so /Applications/exelis/idl/bin/bin.darwin.x86 64/ 
» ep icy.dlm icy.dll C:\Program Files\Exelis\id183\bin\bin.x86_64\ 


— Append to the IDL_DLM_PATH environment variable the directory name 
containing icy.dlm and icy.so or icy.dll: 
setenv IDL _DLM PATH "<IDL_ DEFAULT>: path_to_ directory containing icy.d1m_” 


Warning: with regards to the Icy source directory, icy/src/icy, do not invoke IDL 
from the directory, do not register the directory, and do not append IDL_DLM_PATH 
to the directory. This directory contains an “icy.dlm” but no “icy.so.” 
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NAIE> How Does It Work? (3) 
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When a user invokes a call to a DLM routine: 


1. IDL calls... 
2. the interface routine in the shared object 
library, linked against... 
3. CSPICE, which performs its function and 
returns the result... 
4.to IDL... 


... transparent from the user’s perspective. 
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Icy Distribution 
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¢ NAIF distributes the Icy package as an independent product 
analogous to SPICELIB and CSPICE. 
¢ The package includes: 
— the CSPICE source files 
— the Icy interface source code 
— platform specific build scripts for lcy and CSPICE 


— IDL versions of the SPICE cookbook programs, states, tictoc, 
subpt, and simple 


— an HTML based help system for both Icy and CSPICE, with the 
Icy help cross-linked to CSPICE 


— the Icy shared library and DLM file. The system is ready for use 
after installation of these files 


¢ You do not need a C compiler to use Icy. 
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Icy Operation (1) 
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¢ A user may occasionally encounter an IDL math exception: 


6 Program caused arithmetic error: Floating underflow 


— This warning occurs most often as a consequence of CSPICE 
math operations. 


¢ In all known cases, the SIGFPE exceptions caused by 
CSPICE can be ignored. CSPICE assumes numeric underflow 
as zero. 
— Auser can adjust IDL’s response to math exceptions by setting 
the ! EXCEPT variable: 


» ! EXCEPT = 0 suppresses the SIGFPE messages, and even more 
(e.g. a fatal error). 


» !EXCEPT = 1, the default, reports math exceptions on return to the 
interactive prompt. 
¢ NAIF recommends this be used. 
» ! EXCEPT = 2 reports exceptions immediately after executing the 
command. 
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Icy Operation (2) 
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¢ A possible irritant exists in loading kernels using the 
cspice furnsh function. 
— Kernels are loaded into your IDL session, not into your IDL 
scripts. This means: 


» loaded binary kernels remain accessible (“active”) throughout your 
IDL session 


» data from loaded text kernels remain in the kernel pool (in the IDL 
memory space) throughout your IDL session 


— Consequence: some kernel data may be available to one of your 
scripts even though not intended to be so. 
» You could get incorrect results! 


» If you run only one script during your IDL session, there’s no 
problem. 
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Icy Operation (3) 
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¢ Mitigation: two approaches 


— Load all needed SPICE kernels for your IDL session at the 
beginning of the session, paying careful attention to the files 
loaded and the loading order (loading order affects precedence) 


» Convince yourself that this approach will provide ALL of the scripts 
you will run during this IDL session with the appropriate SPICE data 


— At or near the end of every IDL script: 
» include a call to cspice unload for each kernel loaded using 
cspice furnsh 
» or include a call to cspice kclear to remove ALL kernel data from 
the kernel pool loaded using cspice furnsh 
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Icy Vectorization (1) 
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¢ Several common Icy functions include use of vectorized 
arguments, a capability not available in C or FORTRAN 
toolkits. 


— Note: IDL indexes arrays using a base value of zero as opposed 
to FORTRAN, which uses a base value of one. 


» Example: access the first element of an IDL 1XN array using 
array[0], the second element using array[1], etc. 


¢ Example: use Icy to retrieve state vectors and light-time 
values for 1000 ephemeris times. 


— Create an array of 1000 ephemeris times with step size of 10 
hours, starting from July 1, 2005. 


Cspice strzet;,. "July 1, 200s", Start 
et = dindgen( 1000 )*36000.d + start 


continued on next page 
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Icy Vectorization (2) 
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— Retrieve the state vectors and corresponding light times from 
Mars to earth at each et, in the J2000 frame, using LT+S 
aberration correction: 


espice spkezr, ‘Harth', et, "J2Z000", "LT+S", "MARS', state, ltime 


— Access the ith state 6-vector corresponding to the ith ephemeris 
time with the expression 


State. 1 = stavel*;,1] 


¢ Convert the ephemeris time vector ct from the previous 
example to UTC calendar strings with three decimal places 
accuracy. 


format = 'C' 

prec = 3 

CSpiCe SLZUEC, Sl, TOrMaky. precy, Utes tr 
continued on next page 
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Icy Vectorization (3) 
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— The call returns utcstr, an array of 1000 strings each /th string 
the calendar date corresponding to et [i]. Access the ith string of 
utcstr corresponding to the ith ephemeris time with the expression 


UcCetr 2 = Uleetr [il 


¢ Convert the position components of the N state vectors to 
latitudinal coordinates (the first three components of a state 
vector - IDL uses a zero based vector index). 


Cspice reclat, state(0t2;* ly, radius, latitude, dongitude 


— The call returns three double precision variables of type 
Array[1000] (vectorized scalars): radius, latitude, longitude. 
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Simple Icy Example 
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¢ As an example of using Icy with vectorization, calculate and 
plot, in the J2000 inertial frame, the trajectory of the Cassini 
spacecraft from June 20 2004 to December 1 2005. 


7; Construct a meta kernel, "Standard.tm”, which will be used to load the needed 
7; generic kernels: "naif0011.tls," "de421.bsp,” and "pck00010.tpc.” 


7; Load the generic kernels using the meta kernel, and a Cassini spk. 


cspice furnsh, ['standard.tm’, ‘/kernels/cassini/spk/030201AP SK SM546 T45.bsp’ ] 


;; Define the number of divisions of the time interval and the time interval. 
STEP = 10000 

cspice_str2et, [ 'Jun 20, 2004', 'Dec 1, 2005' ] , et 

times = dindgen (STEP) * (et[1]-et[0])/STEP + et[0] 


cspice _spkpos, 'Cassini', times, 'J2000', 'NONE', 'SATURN BARYCENTER', pos, ltime 


7; Plot the resulting trajectory. 
x = pos[0,*] 

y 
z = pos[2,*] 


pos[1,*] 


iplot, x, y, Zz 


cspice kclear 
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Trajectory of the Cassini spacecraft, in the J2000 frame, from June 20 2004 to Dec 1 2005 
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